<!DOCTYPE HTML PUBLIC "-//ORA//DTD CD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>[Chapter 2] 2.13 Exceptions and Exception Handling</TITLE>
<META NAME="author" CONTENT="David Flanagan">
<META NAME="date" CONTENT="Thu Jul 31 15:48:12 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java">
<META NAME="title" CONTENT="Java in a Nutshell">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java in a Nutshell" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch02_12.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 2<br>How Java Differs from C</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch02_14.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13">2.13 Exceptions and Exception Handling</A></h2>

<P CLASS=para>
<A NAME="PROGRAMMING-IN-JAVA4"></A><A NAME="EXCEPTIONS"></A>Exception handing is a significant new feature of Java.
[6]
There are a number of new terms associated with exception
handling.  First, an <I CLASS=emphasis>exception</I> is a signal that
indicates that some sort of exceptional condition (such as
an error) has occurred.  To <I CLASS=emphasis>throw</I> an exception is to
signal an exceptional condition.  To <I CLASS=emphasis>catch</I> an
exception is to handle it--to take whatever actions are
necessary to recover from it.

<blockquote class=footnote>
<P CLASS=para>[6] 
It is similar to, but not quite the same as,
exception handling in C++.
</blockquote>
<P CLASS=para>
Exceptions propagate up through the lexical block
structure of a Java method, and then up the method call
stack.  If an exception is not caught by the block of code
that throws it, it propagates to the next higher
enclosing block of code.  If it is not caught there, it
propagates up again.  If it is not caught anywhere in the
method, it propagates to the invoking method, where it
again propagates through the block structure.  If an
exception is never caught, it propagates all the way to the
<tt CLASS=literal>main()</tt> method from which the program started, and
causes the Java interpreter to print an error message and a
stack trace and exit.

<P CLASS=para>
As we'll see in the subsections below, exceptions make error
handling (and "exceptional condition" handling) more regular
and logical by allowing you to group all your exception
handling code into one place.  Instead of worrying about all
of the things that can go wrong with each line of your code,
you can concentrate on the algorithm at hand and
place all your error handling code (that is, your exception
catching code) in a single place.

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13.1">Exception Objects</A></h3>

<P CLASS=para>
An exception in Java is an object that is an instance of 
some subclass of <tt CLASS=literal>java.lang.Throwable</tt>.
<tt CLASS=literal>Throwable</tt> has two standard subclasses:
<tt CLASS=literal>java.lang.Error</tt> and <tt CLASS=literal>java.lang.Exception</tt>.
[7]
Exceptions that are subclasses of <tt CLASS=literal>Error</tt> generally
indicate linkage problems related to dynamic loading, or
virtual machine problems such as running out of memory.
They should almost always be considered unrecoverable, and
should not be caught.  While the distinction is not always
clear, exceptions that are subclasses of <tt CLASS=literal>Exception</tt>
indicate conditions that may be caught and recovered from.
They include such exceptions as <tt CLASS=literal>java.io.EOFException</tt>,
which signals the end of a file, and <tt CLASS=literal>java.lang.ArrayAccessOutOfBounds</tt>, which indicates
that a program has tried to read past the end of an array.

<blockquote class=footnote>
<P CLASS=para>[7] 
We'll use the term "exception" to refer to any subclass of
<tt CLASS=literal>Throwable</tt>, whether it is actually an
<tt CLASS=literal>Exception</tt> or an <tt CLASS=literal>Error</tt>.
</blockquote>
<P CLASS=para>
Since exceptions are objects, they can contain data and
define methods.  The <tt CLASS=literal>Throwable</tt> object, at the top of
the exception class hierarchy, includes a <tt CLASS=literal>String</tt>
message in its definition and this field is inherited by
all exception classes.  This field is used to store a
human-readable error message that describes the exceptional
condition.  It is set when the exception object is created
by passing an argument to the constructor method.  The
message can be read from the exception with the
<tt CLASS=literal>Throwable.getMessage()</tt> method.  Most exceptions
contain only this single message, but a few add other data.
The <tt CLASS=literal>java.io.InterruptedIOException</tt>, for example,
adds the following field:

<P CLASS=para>
<DIV CLASS=screen>
<P>
<PRE>
public int bytesTransferred;
</PRE>
</DIV>

<P CLASS=para>
This field specifies how much of the I/O was complete before the
exceptional condition occurred.

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13.2">Exception Handling</A></h3>

<P CLASS=para>
<A NAME="TRY-STATEMENT"></A><A NAME="CATCH-STATEMENT"></A><A NAME="FINALLY-CLAUSE"></A>The <tt CLASS=literal>try</tt>/<tt CLASS=literal>catch</tt>/<tt CLASS=literal>finally</tt> statement is
Java's exception handling mechanism.  <tt CLASS=literal>try</tt>
establishes a block of code that is to have its exceptions
and abnormal exits (through <tt CLASS=literal>break</tt>, <tt CLASS=literal>continue</tt>,
<tt CLASS=literal>return</tt>, or exception propagation) handled.  The
<tt CLASS=literal>try</tt> block is followed by zero or more <tt CLASS=literal>catch</tt>
clauses that catch and handle specified types of
exceptions.  The <tt CLASS=literal>catch</tt> clauses are optionally
followed by a <tt CLASS=literal>finally</tt> block that contains 
"clean-up" code.  The statements of a <tt CLASS=literal>finally</tt> block are
guaranteed to be executed, regardless of how the code in the
<tt CLASS=literal>try</tt> block exits.  A detailed example of the
<tt CLASS=literal>try</tt>/<tt CLASS=literal>catch</tt>/<tt CLASS=literal>finally</tt> syntax is shown in
<A HREF="ch02_13.htm#JNUT2-CH-2-EX-2">Example 2.2</A>.

<DIV CLASS=example>
<h4 CLASS=example><A CLASS="TITLE" NAME="JNUT2-CH-2-EX-2">Example 2.2: The try/catch/finally Statement</A></h4>

<DIV CLASS=screen>
<P>
<PRE>
try {
        // Normally this code runs from the top of the block to the bottom 
        // without problems.  But it sometimes may raise exceptions or
        // exit the block via a break, continue, or return statement.
}
catch (SomeException e1) {
        // Handle an exception object e1 of type SomeException
        // or of a subclass of that type. 
}
catch (AnotherException e2) {
        // Handle an exception object e2 of type AnotherException
        // or of a subclass of that type.
}
finally {
        // Always execute this code, after we leave the try clause,
        // regardless of whether we leave it:
        //    1) Normally, after reaching the bottom of the block.
        //    2) With an exception that is handled by a catch.
        //    3) With an exception that is not handled.
        //    4) Because of a break, continue, or return statement.
}
</PRE>
</DIV>

</DIV>

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13.3">try</A></h3>

<P CLASS=para>
The <tt CLASS=literal>try</tt> clause simply establishes a block of code
that is to have its exceptions and abnormal exits (through
<tt CLASS=literal>break</tt>, <tt CLASS=literal>continue</tt>, <tt CLASS=literal>return</tt>, or
exception propagation) handled.  The <tt CLASS=literal>try</tt> clause by
itself doesn't do anything interesting; it is the
<tt CLASS=literal>catch</tt> and <tt CLASS=literal>finally</tt> clauses that do the
exception handling and clean-up operations.

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13.4">catch</A></h3>

<P CLASS=para>
A <tt CLASS=literal>try</tt> block may be followed by zero or more
<tt CLASS=literal>catch</tt> clauses that specify code to handle various
types of exceptions. <tt CLASS=literal>catch</tt> clauses have an unusual
syntax: each is declared with an argument, much like a
method argument.  This argument must be of type
<tt CLASS=literal>Throwable</tt> or a subclass.  When an exception occurs,
the first <tt CLASS=literal>catch</tt> clause that has an argument of the
appropriate type is invoked.  The type of the argument must
match the type of the exception object, or it must be a
superclass of the exception.  This <tt CLASS=literal>catch</tt> argument is
valid only within the <tt CLASS=literal>catch</tt> block, and refers to the
actual exception object that was thrown.

<P CLASS=para>
The code within a <tt CLASS=literal>catch</tt> block should take whatever
action is necessary to cope with the exceptional condition.
If the exception was a <tt CLASS=literal>java.io.FileNotFoundException</tt> 
exception, for example, you might handle it by asking the user 
to check his or her spelling and try again.  Note that it is not 
required to have a <tt CLASS=literal>catch</tt> clause for every possible 
exception--in some cases the correct response is to allow the 
exception to propagate up and be caught by the invoking method. 
In other cases, such as a programming error signaled by
<tt CLASS=literal>NullPointerException</tt>, the correct response is to not
catch the exception at all, but to allow it to propagate and to
have the Java interpreter exit with a stack trace and an
error message.

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13.5">finally</A></h3>

<P CLASS=para>
The <tt CLASS=literal>finally</tt> clause is generally used to clean up
(close files, release resources, etc.) after the <tt CLASS=literal>try</tt>
clause.  What is useful about the <tt CLASS=literal>finally</tt> clause is
that the code in a <tt CLASS=literal>finally</tt> block is guaranteed to be
executed, if any portion of the <tt CLASS=literal>try</tt> block is
executed, regardless of how the code in the <tt CLASS=literal>try</tt>
block completes.  In the normal case, control reaches the
end of the <tt CLASS=literal>try</tt> block and then proceeds to the
<tt CLASS=literal>finally</tt> block, which performs any necessary cleanup.

<P CLASS=para>
If control leaves the <tt CLASS=literal>try</tt> block because of a
<tt CLASS=literal>return</tt>, <tt CLASS=literal>continue</tt>, or <tt CLASS=literal>break</tt> statement,
the contents of the <tt CLASS=literal>finally</tt> block are executed
before control transfers to its new destination.

<P CLASS=para>
If an exception occurs in the <tt CLASS=literal>try</tt> block and there
is a local <tt CLASS=literal>catch</tt> block to handle the exception,
control transfers first to the <tt CLASS=literal>catch</tt> block, and then
to the <tt CLASS=literal>finally</tt> block. If there is not a local
<tt CLASS=literal>catch</tt> block to handle the exception, control
transfers first to the <tt CLASS=literal>finally</tt> block, and then
propagates up to the nearest
<tt CLASS=literal>catch</tt> clause that can handle the exception.

<P CLASS=para>
Note that if a <tt CLASS=literal>finally</tt> block itself transfers control with a
<tt CLASS=literal>return</tt>, <tt CLASS=literal>continue</tt>, or <tt CLASS=literal>break</tt>
statement, or by raising an exception, the pending
control transfer is abandoned, and this new transfer is
processed.  

<P CLASS=para>
Also note that <tt CLASS=literal>try</tt> and <tt CLASS=literal>finally</tt> can be used
together without exceptions or any <tt CLASS=literal>catch</tt> clauses.
In this case, the <tt CLASS=literal>finally</tt> block is simply cleanup
code that is guaranteed to be executed regardless of any
<tt CLASS=literal>break</tt>, <tt CLASS=literal>continue</tt>, or <tt CLASS=literal>return</tt>
statements within the <tt CLASS=literal>try</tt> clause.

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13.6">Declaring Exceptions</A></h3>

<P CLASS=para>
Java requires that any method that can cause a "normal
exception" to occur must either catch the
exception or specify the type of the exception
with a <tt CLASS=literal>throws</tt> clause in the method declaration. 
[8]
Such a <tt CLASS=literal>throws</tt> clause might look like these:

<blockquote class=footnote>
<P CLASS=para>[8] 
C++ programmers should note that Java uses <tt CLASS=literal>throws</tt> where
C++ uses <tt CLASS=literal>throw</tt>.
</blockquote>
<P CLASS=para>
<DIV CLASS=screen>
<P>
<PRE>
public void open_file() throws IOException {
    // Statements here that might generate an uncaught java.io.IOException
}
public void myfunc(int arg) throws MyException1, MyException2 {
    ...
}
</PRE>
</DIV>

<P CLASS=para>
Note that the exception class specified in a
<tt CLASS=literal>throws</tt> clause may be a superclass of the exception
type that is actually thrown.  Thus if a method throws
exceptions <tt CLASS=literal>a</tt>, <tt CLASS=literal>b</tt>, and <tt CLASS=literal>c</tt>, all of which 
are subclasses of <tt CLASS=literal>d</tt>, the <tt CLASS=literal>throws</tt> clause may specify 
all of <tt CLASS=literal>a</tt>, <tt CLASS=literal>b</tt>, and <tt CLASS=literal>c</tt>, or it may simply 
specify <tt CLASS=literal>d</tt>.

<P CLASS=para>
We said above that the <tt CLASS=literal>throws</tt> clause must be used to
declare any "normal exceptions."  This oxymoronic phrase
refers to any subclass of <tt CLASS=literal>Throwable</tt> that is not a
subclass of <tt CLASS=literal>Error</tt> or a subclass of
<tt CLASS=literal>RuntimeException</tt>.  Java does not require these types
of exceptions to be declared because practically any method
can conceivably generate them, and it would quickly become
tedious to properly declare them all.  For example, every
method running on a buggy Java interpreter can throw an
<tt CLASS=literal>InternalError</tt> exception (a subclass of
<tt CLASS=literal>Error</tt>) and it doesn't make sense to have to declare
this in a <tt CLASS=literal>throws</tt> clause for every method.
Similarly, as far as the Java compiler is concerned, any
method that accesses an array can generate an
<tt CLASS=literal>ArrayIndexOutOfBoundsException</tt> exception (a
subclass of <tt CLASS=literal>RuntimeException</tt>).

<P CLASS=para>
The standard exceptions that you often have to
declare are <tt CLASS=literal>java.io.IOException</tt> and a number of its
more specific subclasses.
<tt CLASS=literal>java.lang.InterruptedException</tt> and several other
less commonly used exceptions must also be declared.
How do you know when you
have to declare a <tt CLASS=literal>throws</tt> clause?  One way is to pay
close attention to the documentation for the methods you
call--if any "normal exceptions"
can be thrown, either catch them or declare them.  Another
way to know what exceptions you've got to declare is to
declare none and wait for the compilation errors--the
compiler will tell you what to put in your <tt CLASS=literal>throws</tt>
clause!

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-2-SECT-13.7">Defining and Generating Exceptions</A></h3>

<P CLASS=para>
<A NAME="THROW-STATEMENT"></A>You can signal your own exceptions with the <tt CLASS=literal>throw</tt>
statement.  The <tt CLASS=literal>throw</tt> keyword must be followed by an object
that is <tt CLASS=literal>Throwable</tt> or a subclass.  Often, exception
objects are allocated in the same statement that they are
thrown in:

<P CLASS=para>
<DIV CLASS=screen>
<P>
<PRE>
throw new MyException("my exceptional condition occurred.");
</PRE>
</DIV>

<P CLASS=para>
When an exception is thrown, normal program execution stops
and the interpreter looks for a <tt CLASS=literal>catch</tt> clause that
can handle the exception.  Execution propagates up through
enclosing statements and through invoking functions until
such a handler is found.  Any <tt CLASS=literal>finally</tt> blocks that
are passed during this propagation are executed.

<P CLASS=para>
Using exceptions is a good way to signal and handle errors
in your own code.  By grouping all your error handling and
recover code together within the
<tt CLASS=literal>try</tt>/<tt CLASS=literal>catch</tt>/<tt CLASS=literal>finally</tt> structure, you
will end up with cleaner code that is easier to understand.
Sometimes, when you are throwing an exception, you can use
one of the exception classes already defined by Java API.
Often, though, you will want to define and throw your own
exception types.

<P CLASS=para>
<A HREF="ch02_13.htm#JNUT2-CH-2-EX-3">Example 2.3</A>
shows how you can define your own exception types, throw
them, and handle them.  It also helps clarify how exceptions
propagate.  It is a long example, but worth studying in some
detail. You'll know you understand exception handling if you 
can answer the following: What happens when this program 
is invoked with no argument; with a string argument; and with 
integer arguments 0, 1, 2, and 99?

<DIV CLASS=example>
<h4 CLASS=example><A CLASS="TITLE" NAME="JNUT2-CH-2-EX-3">Example 2.3: Defining, Throwing, and Handling Exceptions</A></h4>

<DIV CLASS=screen>
<P>
<PRE>
// Here we define some exception types of our own.
// Exception classes generally have constructors but no data or 
// other methods.  All these do is call their superclass constructors.
class MyException extends Exception {
  public MyException() { super(); }
  public MyException(String s) { super(s); }
}
class MyOtherException extends Exception {
  public MyOtherException() { super(); }
  public MyOtherException(String s) { super(s); }
}
class MySubException extends MyException {
  public MySubException() { super(); }
  public MySubException(String s) { super(s); }
}
public class throwtest {
  // This is the main() method.  Note that it uses two
  // catch clauses to handle two standard Java exceptions.
  public static void main(String argv[]) {
    int i;
    
    // First, convert our argument to an integer.
    // Make sure we have an argument and that it is convertible.
    try {  i = Integer.parseInt(argv[0]);  }
    catch (ArrayIndexOutOfBoundsException e) { // argv is empty
      System.out.println("Must specify an argument");
      return;
    }
    catch (NumberFormatException e) { // argv[0] isn't an integer
      System.out.println("Must specify an integer argument");
      return;
    }
    
    // Now, pass that integer to method a().
    a(i);
  }
  
  // This method invokes b(), which is declared to throw
  // one type of exception.  We handle that one exception.
  public static void a(int i) {
    try {
      b(i);
    }
    catch (MyException e) {                                      // Point 1
      // Here we handle MyException and its subclass MySubException.
      if (e instanceof MySubException)
        System.out.print("MySubException: ");
      else
        System.out.print("MyException: ");
      System.out.println(e.getMessage());
      System.out.println("Handled at point 1");
    }
  }
  
  // This method invokes c(), and handles one of the two exception
  // types that that method can throw.  The other exception type is
  // not handled, and is propagated up and declared in this method's
  // throws clause.  This method also has a finally clause to finish
  // up the work of its try clause.  Note that the finally clause is
  // executed after a local catch clause, but before a containing
  // catch clause or one in an invoking procedure.
  public static void b(int i) throws MyException {
    int result;
    try {
      System.out.print("i = " + i);
      result = c(i);
      System.out.print(" c(i) = " + result);
    }
    catch (MyOtherException e) {                                 // Point 2
      // Handle MyOtherException exceptions:
      System.out.println("MyOtherException: " + e.getMessage());
      System.out.println("Handled at point 2");
    }
    finally {
      // Terminate the output we printed above with a newline.
      System.out.print("\n");
    }
  }
  
  // This method computes a value or throws an exception.
  // The throws clause only lists two exceptions, because
  // one of the exceptions thrown is a subclass of another.
  public static int c(int i) throws MyException, MyOtherException {
    switch (i) {
    case 0:      // processing resumes at point 1 above
      throw new MyException("input too low");
    case 1:      // processing resumes at point 1 above
      throw new MySubException("input still too low");
    case 99:     // processing resumes at point 2 above
      throw new MyOtherException("input too high");
    default:
      return i*i;
    }
  }
}
</PRE>
</DIV>

</DIV>

</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch02_12.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch02_14.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>Statements</td>
<td width=171 align=center valign=top><a href="index/idx_0.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>Miscellaneous Differences</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
